HPAVC

home *** CD-ROM | disk | FTP | other *** search

/ HPAVC / HPAVC CD-ROM.iso / XLIBP202.ZIP / XLIB2.DOC < prev next >

Wrap

Text File | 1995-01-26 | 40KB | 938 lines

╔═══════════════════════════════════════════════════════════════════════════╗ ║ ║ ║ XLIB v2.0 - Graphics Library for Borland/Turbo Pascal 7.0 ║ ║ ║ ║ Tristan Tarrant - tristant@cogs.susx.ac.uk ║ ║ ║ ╠═══════════════════════════════════════════════════════════════════════════╣ ║ ║ ║ Credits ║ ║ ║ ║ Themie Gouthas ║ ║ ║ ║ Matthew MacKenzie ║ ║ ║ ║ Tore Bastiansen ║ ║ ║ ║ Andy Tam ║ ║ ║ ║ Douglas Webb ║ ║ ║ ║ John Schlagel ║ ║ ║ ╠═══════════════════════════════════════════════════════════════════════════╣ ║ ║ ║ I informally reserve all rights to the code in XLIB ║ ║ Rights to contributed code is also assumed to be reserved by ║ ║ the original authors. ║ ║ ║ ╚═══════════════════════════════════════════════════════════════════════════╝ ╔═══════════════════════════════════════════════════════════════════════════╗ ║ DISCLAIMER ║ ╚═══════════════════════════════════════════════════════════════════════════╝ This library is distributed AS IS. The author/s specifically disclaim any responsibility for any loss of profit or any incidental, consequential or other damages. ╔═══════════════════════════════════════════════════════════════════════════╗ ║ INTRODUCTION ║ ╚═══════════════════════════════════════════════════════════════════════════╝ XLIB is a "user supported freeware" graphics library specifically designed with game programming in mind. It has been placed in the public domain for the benefit of all, and represents *MANY* hours of work so it is requested that all users comply with the the wishes of the author/s as specified in the individual modules and: a) To leave the code in the public domain b) Not distribute any modified or incomplete versions of this library New contribution and comments are welcome and hopefully there will be more releases as the code evolves. Finally, do not trust this excuse for a manual if in doubt, as this code has undergone several revisions. The place to get the answers is in the code itself. ╔═══════════════════════════════════════════════════════════════════════════╗ ║ REQUIREMENTS ║ ╚═══════════════════════════════════════════════════════════════════════════╝ Minimum requirements 386 processor, VGA, Borland/Turbo Pascal v7.0 ╔═══════════════════════════════════════════════════════════════════════════╗ ║ GENERAL FEATURES ║ ╚═══════════════════════════════════════════════════════════════════════════╝ Support for a number of 256 colour tweaked graphics mode resolutions : 320x200 320x240 360x200 360x240 376x282 320x400 320x480 360x400 360x480 360x360 376x308 376x564 256x200 256x240 256x224 256x256 360x270 400x300 Please note that some of these resolutions best suit monitors with adjustable vertical height. Virtual screens larger than the physical screen (memory permitting) that can be panned at pixel resolution in all directions A split screen capability Text functions supporting 8x8 and 8x14 ROM fonts and user defined fonts Support for page flipping Graphics primitives such as line and rectangle drawing functions and of course bit block manipulation functions Virtual VSync Handler Compression and archiving GIF/BMP loading and saving ╔═══════════════════════════════════════════════════════════════════════════╗ ║ BUILDING THE LIBRARIES ║ ╚═══════════════════════════════════════════════════════════════════════════╝ To compile XLIB use the provided makefile. Just put all of the XLIB files in the same directory and type MAKE at the DOS prompt. This will build all the libraries and examples. If Borland Pascal isn't in your path just edit the makefile where indicated. BP 7.0 and TASM are required to compile the libraries. If you want to make units with full debug information, compile with MAKE -DDEBUG To make the DPMI versions of the units, compile with MAKE -DDPMI To make the help (XLIB2.TPH) file you need ScanHelp. I used version 3.26. MAKE HELP ╔═══════════════════════════════════════════════════════════════════════════╗ ║ USING THE LIBARY WITH YOUR PROGRAMS ║ ╚═══════════════════════════════════════════════════════════════════════════╝ Using the XLIB library in your programs is simple. Just include the XLIB units in the uses statement at the beginning of your program which will make all the procedures and functions composing the XLIB library available. ╔═══════════════════════════════════════════════════════════════════════════╗ ║ GLOBAL CONSTANTS, VARIABLES AND TYPES ║ ╚═══════════════════════════════════════════════════════════════════════════╝ Type Vertex = record x, y : word; end; - Vertex record used for xpolygon. VBMInfoStruc = record Size, ImageWidth, ImageHeight : word; end; - Video Bitmap Structure VBMAlignmentStruc = record ImagePtr, MaskPtr : word; end; - Video Bitmap Structure to data in VRAM AlignmentHeader = record size, ImageWidth, ImageHeight : word; alignments : array[0..3] of record ImagePtr, MaskPtr : word; end; end; - Video Bitmap VRAM stuff LBMHeader = record width, height : byte; end; - Linear/Planar Bitmap header PAlignmentHeader = ^AlignmentHeader; - Pointer to VBM VRAM info Const XMode320x200 = 0; 320x200x256 colors - 4.0+ pages XMode320x240 = 1; 320x240x256 colors - 3.4+ pages - Square Pixels XMode360x200 = 2; 360x200x256 colors - 3.6+ pages XMode360x240 = 3; 360x240x256 colors - 3.0+ pages XMode376x282 = 4; 376x282x256 colors - 2.4+ pages - Square Pixels XMode320x400 = 5; 320x400x256 colors - 2.0+ pages XMode320x480 = 6; 320x480x256 colors - 1.7+ pages XMode360x400 = 7; 360x400x256 colors - 1.8+ pages XMode360x480 = 8; 360x480x256 colors - 1.5+ pages XMode360x360 = 9; 360x360x256 colors - 2.0+ pages XMode376x308 = 10; 376x308x256 colors - 2.2+ pages XMode376x564 = 11; 376x564x256 colors - 1.2+ pages XMode256x200 = 12; 256x200x256 colors - 5.1+ pages XMode256x240 = 13; 256x240x256 colors - 4.2+ pages XMode256x224 = 14; 256x224x256 colors - 4.5+ pages XMode256x256 = 15; 256x256x256 colors - 4.0 pages XMode360x270 = 16; 360x270x256 colors - 2.6+ pages - Square Pixels XMode400x300 = 17; 400x300x256 colors - 2.1+ pages - Square Pixels LastMode = 17; Number of modes RBackward = 0; Rotate Palette backward RForward = 1; Rotate Palette forward InvalidXMode = -1; The selected XMode doesn't exist (returned by xsetmode ). Error = 1; Possible value for ErrorValue AlignData = 6; Used by VBM routines LeftPressed = 1; Possible value for MouseButtonStatus RightPressed = 2; Possible value for MouseButtonStatus Var InGraphics, - 1 if in a graphics mode, 0 otherwise ErrorValue, - Set by every routine to indicate success or failure FontDriverActive, - Set after a call to xtextinit CharHeight, - Height of the current character set CharWidth, - Width of the current character set FirstChar, - First character in character set UserChHeight, - Height of the User Font UserChWidth, - Width of the User Font UserFirstCh, - First character in User's font DoubleScanFlag : Byte; - 1 if mode is double-scanned, 0 otherwise CurrXMode, - Contains value of current graphics mode ScrnPhysicalByteWidth, - Physical width of the screen in bytes ( ie : group of 4 pixels ) ScrnPhysicalPixelWidth, - Physical width of the screen in pixels ScrnPhysicalHeight, - Physical height of the screen in pixels SplitScrnOffs, - Offset in VRAM of Split Screen SplitScrnScanLine, - Screen Line where Split Screen is displayed SplitScrnVisibleHeight, - Height of the visible part of the split screen SplitScrnActive, - Contains 1 if SplitScreen is visible,0 otherwise Page0Offs, - Offset in VRAM of 1st page Page1Offs, - Offset in VRAM of 2nd page ( xsetdoublebuffer ) Page2Offs, - Offset in VRAM of 3rd page ( xsettriplebuffer ) ScrnLogicalByteWidth, - Width in bytes ( groups of 4 pixels ) of a page ScrnLogicalPixelWidth, - Width in pixels of a page ScrnLogicalHeight, - Height in pixels of a page MaxScrollX, - Maximum value for left edge of screen MaxScrollY, - Maximum value for top edge of screen DoubleBufferActive, - Set by xsetdoublebuffer TripleBufferActive, - Set by xsettriplebuffer VisiblePageIdx, - Number of the Visible Page HiddenPageOffs, - Offset of the Hidden page VisiblePageOffs, - Offset of the Visible page WaitingPageOffs, - Offset of the Waiting page NonVisualOffs, - Offset of start of unused VRAM TopClip, - Top clipping edge BottomClip, - Bottom clipping edge LeftClip, - Left clipping edge RightClip, - Right clipping edge PhysicalStartPixelX, - X coordinate of top left pixel PhysicalStartByteX, - X coordinate of top left pixel /4 PhysicalStartY, - Y coordinate of top left pixel VsyncHandlerActive, - set to 1 if the VSync handler has been installed MouseInstalled, - set to 1 if the Mouse handler has been installed MouseHidden, - set to 1 if after a call to xhidemouse MouseButtonStatus, - information on the button presses MouseButtonCount, - the number of buttons on the mouse MouseX, - X coordinate of mouse pointer MouseY, - Y coordinate of mouse pointer MouseVersion : word; - Version of Mouse driver MouseFrozen, - set to 1 if you want to update the mouse manually MouseColor : byte; - color of the mouse pointer ╔═══════════════════════════════════════════════════════════════════════════╗ ║ XLIB2 : EXPORTED PROCEDURES AND FUNCTIONS ║ ╚═══════════════════════════════════════════════════════════════════════════╝ ╔═══════════════════════════════════════════════════════════════════════════╗ ║ GENERAL PROCEDURES AND FUNCTIONS ║ ╚═══════════════════════════════════════════════════════════════════════════╝ Function XSetMode( Mode, WidthInPixels : Word ) : Word; -------------------------------------------------------- Mode - The required mode WidthInPixels - The width of the logical screen This function initialises the graphics system, setting the apropriate screen resolution and allocating a virtual screen. The virtual screen allocated may not necessarily be of the same size as specified in the WidthInPixels parameter as it is rounded down to the nearest multiple of 4. The function returns the actual width of the allocated virtual screen in pixels if a valid mode was selected otherwise returns XMODEINVALID. Saves virtual screen pixel width in ScrnLogicalPixelWidth. Saves virtual screen byte width in ScrnLogicalByteWidth. Physical screen dimensions are set in ScrnPhysicalPixelWidth. ScrnPhysicalByteWidth and ScrnPhysicalHeight. Other global variables set are CurrXMode,MaxScrollX, MaxScrollY, InGraphics. The variable SplitScrnScanline is also initialized to zero. Procedure XSelectDefaultPlane( Plane : Byte ); ---------------------------------------------- Enables default Read/Write access to a specified plane Procedure XSetSplitscreen( Line : Word ); ----------------------------------------- line - The starting scan line of the required split screen. This function activates Mode X split screen and sets starting scan line The split screen resides on the bottom half of the screen and has a starting address of A000:0000 in video RAM. It also Updates Page0Offs to reflect the existence of the split screen region ie MainScrnOffset is set to the offset of the first pixel beyond the split screen region. Other variable set are Page1Offs which is set to the same value as Page0Offs (see graphics call sequence below), ScrnLogicalHeight,ScrnPhysicalHeight, SplitScrnScanLine and MaxScrollY. This function cannot be called after double buffering has been activated, it will return an error. To configure your graphics environment the sequence of graphics calls is as follows although either or both steps b and c may be omitted: a) xsetmode b) xsetsplitscreen c) xsetdoublebuffer Thus when you call this function successfully, double buffering is not active so Page1Offs is set to the same address as Page0Offs. WARNING: If you use one of the high resolution modes (376x564 as an extreme example) you may not have enough video ram for split screen and double buffering options since VGA video RAM is restricted to 64K. Procedure XSetStartAddr( X, Y : Word ); --------------------------------------- X,Y - coordinates of top left corner of physical screen within current virtual screen. Set Mode X non split screen physical start address within current virtual page. X must not exceed (Logical screen width - Physical screen width) ie MaxScrollX and Y must not exceed (Logical screen height - Physical screen height) ie MaxScrollY Procedure XHideSplitscreen; --------------------------- This function hides an existing split screen by setting its starting scan line to the last physical screen scan line. ScreenPhysicalHeight is adjusted but the SplitScreenScanLine is not altered as it is required for restoring the split screen at a later stage. WARNING: Only to be used if SplitScrnLine has been previously called The memory for the initial split screen is reserved and the size limitations of certain modes means any change in the split screen scan line will encroach on the split screen ram. Procedure XShowSplitscreen; --------------------------- Restores split screen start scan line to the initial split screen starting scan line as set by SplitScrnScanLine. ScreenPhysicalHeight is adjusted. WARNING: Only to be used if SplitScrnLine has been previously called The memory for the initial split screen is reserved and the size limitations of certain modes means any change in the split screen scan line will encroach on the split screen ram. Procedure XAdjustSplitscreen( Line : Word ); -------------------------------------------- line - The scan line at which the split screen is to start. Sets the split screen start scan line to a new scan line. Valid scan lines are between the initial split screen starting scan line and the last physical screen scan line. ScreenPhysicalHeight is also adjusted. WARNING: Only to be used if SplitScrnLine has been previously called The memory for the initial split screen is reserved and the size limitations of certain modes means any change in the split screen scan line will encroach on the split screen ram. Procedure XSetDoubleBuffer( PageHeight : Word ); ------------------------------------------------ PageHeight - The height of the two double buffering virtual screens. Returns - The closest possible height to the specified. This function sets up two double buffering virtual pages. ErrorValue is set according to the success or failure of this command. Other variables set are: Page1Offs - Offset of second virtual page NonVisualOffs - Offset of first non visible video ram byte DoubleBufferActive - Flag PageAddrTable - Table of Double buffering pages start offsets ScrnLogicalHeight - Logical height of the double buffering pages MaxScrollY - Max vertical start address of physical screen within the virtual screen WARNING: If you use one of the high resolution modes (376x564 as an extreme example) you may not have enough video ram for split screen and double buffering options since VGA video RAM is restricted to 64K. Procedure XSetTripleBuffer( PageHeight : word ); ------------------------------------------------ This procedure behaves like xdoublebuffer, but when used with xinstallvsynchandler you can draw immediately after a page flip. When xpageflip is called, VisiblePageOffs is set to the page that will be display next vsync. Until then, WaitingPageOffs will be displayed. You can draw to HiddenPageOffs . Procedure XPageFlip( X, Y : Word ); ----------------------------------- X,Y - coordinates of top left corner of physical screen within the the hidden virtual screen if double buffering is active, or the current virtual screen otherwise. Sets the physical screen start address within currently hidden virtual page and then flips pages. If double buffering is not active then this function is functionally equivalent to xsetstartaddr. X must not exceed (Logical screen width - Physical screen width) ie MaxScrollX and Y must not exceed (Logical screen height - Physical screen height) ie MaxScrollY Procedure XSetClipRect( Left, Top, Right, Bottom : Word ); ---------------------------------------------------------- Defines the clipping rectangle for clipping versions of planar and video bitmap puts. Left and Right are in bytes (i.e. multiples of 4 pixels), Top and Bottom are in pixels. Thus the following call xsetcliprect(2,4,40,150); Would set the clipping rectangle to (8,4,160,150) NOTE: Compiled bitmaps cannot be clipped. Procedure XTextMode; -------------------- Disables graphics mode. Procedure XWaitVsync; --------------------- Waits for a vsync to occur : i.e. when the electron beam that's refreshing the video image has reached the bottom of the screen. ╔═══════════════════════════════════════════════════════════════════════════╗ ║ DRAWING PROCEDURES AND FUNCTIONS ║ ╚═══════════════════════════════════════════════════════════════════════════╝ Procedure XLine( x1, y1, x2, y2, Color, PgOffs : word ); -------------------------------------------------------- Draw a line with the specified end points in the page starting at offset PageBase. No Clipping is performed. Procedure XPutPix( X,Y,PgOfs,Color:word ); ------------------------------------------ Draw a point of specified colour at coordinates X,Y within the virtual page starting at offset PgOfs. Function XGetPix( x,y,PageBase:word ) : word; ---------------------------------------------- Read a point of at coordinates X,Y within the virtual page starting at offset PageOffset. Procedure XRectFill( StartX,StartY,EndX,EndY,PageBase,Color:word ); ------------------------------------------------------------------- StartX,StartY - Coordinates of upper left hand corner of rectangle EndX,EndY - Coordinates of lower right hand corner of rectangle PageBase - Offset of virtual screen Color - Color of the box. Mode X rectangle fill routine. Procedure XRectPattern( StartX,StartY,EndX,EndY,PageBase:word; var Pattern); ---------------------------------------------------------------------------- StartX,StartY - Coordinates of upper left hand corner of rectangle EndX,EndY - Coordinates of lower right hand corner of rectangle PageBase - Offset of virtual screen Pattern - Untyped variable for the user defined pattern (16 bytes) Mode X rectangle 4x4 pattern fill routine. Upper left corner of pattern is always aligned to a multiple-of-4 row and column. Works on all VGAs. Uses approach of copying the pattern to off-screen display memory, then loading the latches with the pattern for each scan line and filling each scan line four pixels at a time. Fills up to but not including the column at EndX and the row at EndY. No clipping is performed. Warning the VGA memory locations PATTERNBUFFER (A000:FFFc) to A000:FFFF are reserved for the pattern buffer Procedure XCpVidPage( SourceOffs, DestOffs : word ); ---------------------------------------------------- SourceOffs - Offset of source video page DestOffs - Offset of destination page Copies the contents of page SourceOffs to DestOffs. Twice as fast as a xcpvidrect would be (because it uses less parameters, so less stack work is required). Procedure XCpVidRect( SrcStartX,SrcStartY,SrcEndX,SrcEndY,DestStartX, SourcePageBase,DestPageBase,SourceBitmapW,DestBitmapW:word ); --------------------------------------------------------------------- StartX,StartY - Coordinates of upper left hand corner of source rectangle EndX,EndY - Coordinates of lower right hand corner of source rectangle DestStartX,DestStartY - Coordinates of rectangle destination SourcePageBase - source rectangle page offset DestPageBase - destination rectangles page offset SourceBitmapWidth - width of bitmap within the source virtual screen containing the source rectangle DestBitmapWidth - width of bitmap within the dest. virtual screen containing the destination rectangle Mode X display memory to display memory copy routine. Left edge of source rectangle modulo 4 must equal left edge of destination rectangle modulo 4. Works on all VGAs. Uses approach of reading 4 pixels at a time from the source into the latches, then writing the latches to the destination. Copies up to but not including the column at SrcEndX and the row at SrcEndY. No clipping is performed. Results are not guaranteed if the source and destination overlap. Procedure XShiftRect( SrcLeft,SrcTop,SrcRight,SrcBottom,DestLeft,DestTop, ScreenOffs:word ); ------------------------------------------------------------------------- SrcLeft, SrcTop - Coordinates of upper left hand corner of rectangle SrcRight, SrcBottom - Coordinates of lower right hand corner of rectangle DestLeft, DestTop - Coordinates of upper left corner of destination ScreenOffs - Offset of virtual screen This function copies a rectangle of VRAM onto another area of VRAM, even if the destination overlaps with the source. It is designed for scrolling text up and down, and for moving large areas of screens around in tiling systems. It rounds all horizontal coordinates to the nearest byte (4-column chunk) for the sake of speed. This means that it can NOT perform smooth horizontal scrolling. For that, either scroll the whole screen (minus the split screen), or copy smaller areas through system memory using the functions in the XBM2 module. SrcRight is rounded up, and the left edges are rounded down, to ensure that the pixels pointed to by the arguments are inside the the rectangle. That is, SrcRight is treated as (SrcRight+3) >> 2, and SrcLeft as SrcLeft >> 2. The width of the rectangle in bytes (width in pixels / 4) cannot exceed 255. Procedure XCircle( Left, Top, Diameter, Color, ScreenOffs:word ); ----------------------------------------------------------------- Draws a circle with the given upper-left-hand corner and diameter, which are given in pixels. Procedure XFilledCircle( Left, Top, Diameter, Color, ScreenOffs:word ); ----------------------------------------------------------------------- Draws a filled circle with the given upper-left-hand corner and diameter. xtriangle --------- procedure xtriangle( x0, y0, x1, y1, x2, y2 : integer; color, PageBase : word ); This function draws a filled triangle which is clipped to the current clipping window defined by TopClip,BottomClip,LeftClip,RightClip. Remember: the X clipping variable are in byteS not PIXELS so you can only clip to 4 pixel byte boundaries. xpolygon -------- procedure xpolygon( var vertices; numvertices : integer; color, PageBase : word ); This function is similar to the triangle function but draws convex polygons. The vertices are supplied as an array of vertices. NOTE: a convex polygon is one such that if you draw a line from any two vertices, every point on that line will be within the polygon. This function works by splitting up a polygon into its component triangles and calling the triangle routine above to draw each one. Performance is respectable but a custom polygon routine might be faster. xfloodfill ---------- Function xfloodfill(int x, int y, unsigned ofs, int color) : integer; This function performs the familiar flood filling used by many paint programs and of course the Borland BGI's flood fill function. The pixel at x,y and all adjacent pixels of the same color are filled to the new color. Filling stops when there are no more adjacent pixels of the original pixel's color. The function returns the number of pixels that have been filled. xboundaryfill ------------- Function xboundaryfill( x, y, ofs, boundary, color : integer ) : integer; This function is a variant of the flood fill described above. This function, unlike the above function, can fill across color boundaries. Filling stops when the area being filled is fully enclosed by pixels of the color boundary. Again, this function returns the number of pixels filled. ╔═══════════════════════════════════════════════════════════════════════════╗ ║ PALETTE PROCEDURES AND FUNCTIONS ║ ╚═══════════════════════════════════════════════════════════════════════════╝ There are two sets of procedures in function that deal with changing the palette : the Struc and the Raw ones. The Struc procs work with what is also referred to as an annotated buffer which contains the first colour and the number of colours stored apart from the DAC data. Raw buffers just contain the DAC data. Procedure XGetPalStruc( var PalBuff; NumColors,StartColor:word ); ----------------------------------------------------------------- Read DAC palette into annotated type buffer with interrupts disabled ie byte colours to skip, byte colours to set, r1,g1,b1,r1,g2,b2...rn,gn,bn WARNING: memory for the palette buffers must all be pre-allocated Procedure XGetPalRaw( Var PalBuff; NumColors,StartColor:word ); --------------------------------------------------------------- Read DAC palette into raw buffer with interrupts disabled ie byte r1,g1,b1,r1,g2,b2...rn,gn,bn WARNING: Memory for the palette buffers must all be pre-allocated. Procedure XPutPalStruc( Var CompPalBuff ); ------------------------------------------ Write DAC palette from annotated type buffer with interrupts disabled ie byte colours to skip, byte colours to set, r1,g1,b1,r1,g2,b2...rn,gn,bn Procedure XTransposePalStruc( Var CompPalBuff; StartColor:word ); ----------------------------------------------------------------- Write DAC palette from annotated type buffer with interrupts disabled starting at a new palette index. Procedure XPutPalRaw( Var PalBuff; NumColors,StartColor:word ); --------------------------------------------------------------- Write DAC palette from raw buffer with interrupts disabled ie byte r1,g1,b1,r1,g2,b2...rn,gn,bn Procedure XSetRGB( ColorIndex,R,G,B:byte ); ------------------------------------------- Set the RGB components of a vga color Procedure XRotPalStruc( Var PalBuff; Direction:word ); ------------------------------------------------------ Rotate annotated palette buffer entries. Direction 0 = backward, 1 = forward. Procedure XRotPalRaw( Var PalBuff; Direction, NumColors:word ); --------------------------------------------------------------- Rotate a raw palette buffer. Direction 0 = backward, 1 = forward. Function XCpContrastPalStruc( Var PalSrcBuff,PalDestBuff; Intensity:byte ) : word; ----------------------------------------------------------------------------------- Copy one annotated palette buffer to another making the intensity adjustment. Used in fading in and out fast and smoothly. Procedure XPutContrastPalStruc( Var CompPalBuff; Intensity:byte ); ------------------------------------------------------------------ Write DAC palette from annotated type buffer with specified intensity adjustment (ie palette entries are decremented where possible by intensity units). Designed for fading in or out a palette without using an intermediate working palette buffer ! (Slow but memory efficient ... OK for small pal strucs) ╔═══════════════════════════════════════════════════════════════════════════╗ ║ TEXT PROCEDURES AND FUNCTIONS ║ ╚═══════════════════════════════════════════════════════════════════════════╝ Note : the fonts supplied with XLIB2 come mostly from Kai Rohrbacher's ANIVGA package. Function XCharPut( Chr:char; X, Y, ScrnOffs, Color:word ) : byte; ------------------------------------------------------------------ Draw a text character at the specified location with the specified color. ch - char to draw x,y - screen coords at which to draw ch ScrnOffs - Starting offset of page on whih to draw Color - Color of the text WARNING: xtextinit must be called before using this function Procedure XSetFont( FontID : word ); ------------------------------------ Procedure xsetfont(FontId : word); Select the working font where 0 = VGA ROM 8x8, 1 = VGA ROM 8x14 2 = User defined bitmapped font. WARNING: A user font must be registered before setting FontID 2 Procedure XTextInit; -------------------- Initializes the Mode X text driver and sets the default font (VGA ROM 8x8) Procedure XRegisterUserFont( var FontToRegister ); -------------------------------------------------- Register a user font for later selection. Only one user font can be registered at any given time. Registering a user font deregisters the previous user font. User fonts may be at most 8 pixels wide. USER FONT STRUCTURE Word: ascii code of first char in font Byte: Height of chars in font Byte: Width of chars in font n*h*Byte: the font data where n = number of chars and h = height of chars WARNING: The onus is on the program to ensure that all characters drawn whilst this font is active, are within the range of characters defined. Function XGetCharWidth( ch : char ) : byte; -------------------------------------------- Returns the width in pixels of character ch in the currently selected font. Function XPrintf( x, y, ScrnOffs, Color : word; s : string ) : integer; ------------------------------------------------------------------------ x,y - screen coords at which to draw ch ScrnOffs - Starting offset of page on whih to draw Color - Color of the text s - The string to be displayed Displays the string s at coordinates x,y on page ScrnOffs in Color. Returns the width of the string in pixels. Procedure XBgPrintf( x, y, ScrnOffs, fgcolor, bgcolor : word; s : string ); --------------------------------------------------------------------------- x,y - screen coords at which to draw ch ScrnOffs - Starting offset of page on whih to draw fgcolor - Color of the text foreground bgcolor - Color of the text background s - The string to be displayed Same as XPrintf but erases the background of the string with color bgcolor. ╔═══════════════════════════════════════════════════════════════════════════╗ ║ MOUSE PROCEDURES AND FUNCTIONS ║ ╚═══════════════════════════════════════════════════════════════════════════╝ Procedure XDefineMouseCursor( var MouseDef; MouseColor:byte ); -------------------------------------------------------------- MouseDef - a buffer of 14 characters containing a bitmask for all the cursor's rows. MouseColor - The colour to use when drawing the mouse cursor. Define a mouse cursor shape for use in subsequent cursor redraws. XMouse has a hardwired mouse cursor size of 8 pixels across by 14 pixels down. WARNING: This function assumes MouseDef points to 14 bytes. Note: Bit order is in reverse. ie bit 7 represents pixel 0 .. bit 0 represents pixel 7 in each MouseDef byte. procedure XMouseInit; --------------------- Initialize the mouse driver functions and install the mouse event handler function. This is the first function you must call before using any of the mouse functions. This mouse code uses the fastest possible techniques to save and restore mouse backgrounds and to draw the mouse cursor. WARNING: This function uses and updates NonVisualOffset to allocate video ram for the saved mouse background. LIMITATIONS: No clipping is supported horizontally for the mouse cursor No validity checking is performed for NonVisualOffs **WARNING** You must Hide or at least Freeze the mouse cursor while drawing using any of the other XLIB procedures since the mouse handler may modify vga register settings at any time. VGA register settings are not preserved which will result in unpredictable drawing behavior. If you know the drawing will occur away from the mouse cursor set MouseFrozen to 1, do your drawing then set it to 0. Alternatively call xhidemouse, perform your drawing and then call xshowmouse. Another alternative is to disable interrupts while drawing but usually drawing takes up alot of time and having interrupts disabled for too long is not a good idea. If you are using the Virtual VSync Handler and just updating the palette you don't need to freeze the mouse. Procedure XMouseWindow( x0, y0, x1, y1:word ); ---------------------------------------------- Defines a mouse window. The mouse can't move outside the boundaries specified. procedure XShowMouse; --------------------- Makes the cursor visible if it was previously hidden. Procedure XHideMouse; --------------------- Makes the cursor hidden if it was previously visible. Procedure XMouseRemove; ----------------------- Stop mouse event handling and remove the mouse handler. NOTE: This function MUST be called before quitting the program if a mouse handler has been installed Procedure XPositionMouse( X, Y : word ); ---------------------------------------- Positions the mouse at a specified location Procedure XUpdateMouse; ----------------------- Forces the mouse position to be updated and cursor to be redrawn. Note: this function is useful when you have set MouseFrozen to true. Allows the cursor position to be updated manually rather than automatically by the installed handler. ╔═══════════════════════════════════════════════════════════════════════════╗ ║ VSYNC HANDLER PROCEDURES AND FUNCTIONS ║ ╚═══════════════════════════════════════════════════════════════════════════╝ The xvsync module uses timer 0 to simulate a vertical retrace interrupt. It's designed to significantly reduce the idle waiting time in Xlib. Why simulate the VRT interrupt ? Simply because a true VRT interrupt is not implemented on many VGA cards. Using a VRT interrupt as opposed to polling, can result in huge performance improvements for your code and help make animation much smoother than it would be using polling. Normally xlib waits for vsync when xpageflip, xsetstartaddress or xputpal??? is called. This waiting period could be better utilized to do housekeeping calculations or whatever. The xputpal??? functions also doesn't work very smoothly in conjunction with other functions that wait for the vertical retrace since each function introduces its own VRT delay. When using the vsync handler, the VRT delay is reduced to the absolute minumum which can result in a huge performance boost for your programs. When using double buffering, you may still have to wait before drawing, but you could do as much other work as possible, like this: xpageflip(...) ... <animate the palette> <do some collision detection and 3D calculations> <read the joystick> ... <draw next frame> ... Procedure XInstallVSyncHandler( VrtsToSkip : word ); ---------------------------------------------------- This function installs the vsync handler using timer 0. It's called about 100 microseconds before every vertical retrace. The VrtsToSkip value (>=1) defines the delay in VRT's between consecutive physical screen start address changes, thus allowing you to limit the maximum frame rate for page flips in animation systems. The frame rate is calculated as Vertical refresh rate / VrtsToSkip, eg for 320x240 mode which refreshes at 60Hz a VrtsToSkip value of 3 will result in a maximum page flipping rate of 20Hz (frames per second) WARNING: Be sure to remove it before exiting. When used with a debugger, the system clock may speed up. Procedure XRemoveVSyncHandler; ------------------------------ This routine MUST be called before exiting (or aborting) the program, or your system will crash. Procedure XSetUserVSyncHandler( handler : pointer ); --------------------------------------------------- Installs a user routine to be called once each vertical retrace. The user handler has its own stack of 256 bytes. WARNING: This installs an interrupt driven handler, beware of the following: Only 8086 registers are preserved. If you're using 386 code, save all the 386 regs. Don't do any drawing. Don't call any DOS functions. So why use it? Well, you can update global variables if you're careful. And it's nice for palette animation. You can even do fades while loading from disk. You should use this instead of installing your own int08h routine and chain to the original.